/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.help;
import org.eclipse.help.IContext;
import org.eclipse.help.IHelp;
import org.eclipse.jface.action.IAction;
import org.eclipse.swt.events.HelpListener;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Menu;
import org.eclipse.swt.widgets.MenuItem;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.commands.ICommand;
import org.eclipse.ui.internal.help.WorkbenchHelpSystem;
/**
* Provides methods for accessing the help UI.
* <p>
* The help UI is optional, to allow applications to be configured without one.
* </p>
* <p>
* The various <code>setHelp</code> methods allow context help to be hooked in
* to SWT menus, menu items, and controls, and into JFace actions. This involves
* furnishing a help context id. When the user requests help for one of the
* established widgets (for instance, by hitting F1), the context id is
* retrieved and passed to the help UI using
* <code>WorkbenchHelp.displayContext(helpContext, xposition, yposition)</code>.
* </p>
* <p>
* In cases more dynamic situations, clients may hook their own help listener
* and call <code>WorkbenchHelp.displayContext</code> with an
* <code>IContext</code>.
* </p>
* <p>
* This class provides static methods only; it is not intended to be
* instantiated or subclassed.
* </p>
*
* @deprecated marked for deletion, see Bug 442959, clients should use
* <code>IWorkbenchHelpSystem</code> instead
*
* @see org.eclipse.help.HelpSystem
* @see org.eclipse.ui.help.IWorkbenchHelpSystem
* @see org.eclipse.ui.IWorkbench#getHelpSystem()
* @noinstantiate This class is not intended to be instantiated by clients.
* @noextend This class is not intended to be subclassed by clients.
* @noreference This class is not intended to be referenced by clients.
*/
@Deprecated
public class WorkbenchHelp {
/**
* This class is not intented to be instantiated
*/
private WorkbenchHelp() {
}
/**
* Displays the entire help bookshelf.
* <p>
* Ignored if no help UI is available.
* </p>
*
* @since 3.0
*/
public static void displayHelp() {
PlatformUI.getWorkbench().getHelpSystem().displayHelp();
}
/**
* Displays context-sensitive help for the given context.
* <p>
* (x,y) coordinates specify the location where the context sensitive
* help UI will be presented. These coordinates are screen-relative
* (ie: (0,0) is the top left-most screen corner).
* The platform is responsible for calling this method and supplying the
* appropriate location.
* </p>
* <p>
* Ignored if no help UI is available.
* </p>
*
* @param context the context to display
* @param x horizontal position
* @param y verifical position
* @since 3.0
*/
public static void displayContext(IContext context, int x, int y) {
PlatformUI.getWorkbench().getHelpSystem().displayContext(context, x, y);
}
/**
* Displays help content for the help resource with the given URL.
* <p>
* This method is called by the platform to launch the help system UI, displaying
* the documentation identified by the <code>href</code> parameter.
* </p>
* <p>
* The help system makes no guarantee that all the help resources can be displayed or how they are displayed.
* </p>
* <p>
* Ignored if no help UI is available.
* </p>
*
* @param href the URL of the help resource.
* <p>Valid href are as described in
* {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
* </p>
* @since 3.0
*/
public static void displayHelpResource(String href) {
PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(href);
}
/**
* Creates a new help listener for the given command. This retrieves the
* help context ID from the command, and creates an appropriate listener
* based on this.
*
* @param command
* The command for which the listener should be created; must
* not be <code>null</code>.
* @return A help listener; never <code>null</code>.
*/
public static HelpListener createHelpListener(ICommand command) {
return WorkbenchHelpSystem.getInstance().createHelpListener(command);
}
/**
* Calls the help support system to display the given help context id.
* <p>
* May only be called from a UI thread.
* <p>
*
* @param contextId the id of the context to display
* @since 2.0
*/
public static void displayHelp(String contextId) {
PlatformUI.getWorkbench().getHelpSystem().displayHelp(contextId);
}
/**
* Displays context-sensitive help for the given context.
* <p>
* May only be called from a UI thread.
* <p>
*
* @param context the context to display
* @since 2.0
*/
public static void displayHelp(IContext context) {
PlatformUI.getWorkbench().getHelpSystem().displayHelp(context);
}
/**
* Returns the help contexts on the given control.
* <p>
* Instances of <code>IContextComputer</code> may use this method
* to obtain the previously registered help contexts of a control.
* </p>
*
* @param control the control on which the contexts are registered
* @return contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>) or an <code>IContextComputer</code> or
* <code>null</code> if no contexts have been set.
* @deprecated as context computers are no longer supported
*/
@Deprecated
public static Object getHelp(Control control) {
return control.getData(WorkbenchHelpSystem.HELP_KEY);
}
/**
* Returns the help contexts on the given menu.
* <p>
* Instances of <code>IContextComputer</code> may use this method
* to obtain the previously registered help contexts of a menu.
* </p>
*
* @param menu the menu on which the contexts are registered
* @return contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>) or an <code>IContextComputer</code> or
* <code>null</code> if no contexts have been set.
* @deprecated as context computers are no longer supported
*/
@Deprecated
public static Object getHelp(Menu menu) {
return menu.getData(WorkbenchHelpSystem.HELP_KEY);
}
/**
* Returns the help contexts on the given menu item.
* <p>
* Instances of <code>IContextComputer</code> may use this method
* to obtain the previously registered help contexts of a menu.
* </p>
*
* @param menuItem the menu item on which the contexts are registered
* @return contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>) or an <code>IContextComputer</code> or
* <code>null</code> if no contexts have been set.
* @deprecated as context computers are no longer supported
*/
@Deprecated
public static Object getHelp(MenuItem menuItem) {
return menuItem.getData(WorkbenchHelpSystem.HELP_KEY);
}
/**
* Returns the help support system for the platform, if available.
*
* @return the help support system, or <code>null</code> if none
* @deprecated Use the static methods on this class and on
* {@link org.eclipse.help.HelpSystem HelpSystem} instead of the IHelp methods
* on the object returned by this method.
*/
@Deprecated
public static IHelp getHelpSupport() {
return WorkbenchHelpSystem.getInstance().getHelpSupport();
}
/**
* Returns whether the context-sensitive help window is currently being
* displayed. Returns <code>false</code> if the help UI has not been
* activated yet.
*
* @return <code>true</code> if the context-sensitive help
* window is currently being displayed, <code>false</code> otherwise
*/
public static boolean isContextHelpDisplayed() {
return PlatformUI.getWorkbench().getHelpSystem().isContextHelpDisplayed();
}
/**
* Sets the given help contexts on the given action.
* <p>
* Use this method when the list of help contexts is known in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param action the action on which to register the computer
* @param contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>)
* @deprecated use setHelp with a single context id parameter
*/
@Deprecated
public static void setHelp(IAction action, final Object[] contexts) {
WorkbenchHelpSystem.getInstance().setHelp(action, contexts);
}
/**
* Sets the given help context computer on the given action.
* <p>
* Use this method when the help contexts cannot be computed in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param action the action on which to register the computer
* @param computer the computer to determine the help contexts for the control
* when F1 help is invoked
* @deprecated context computers are no longer supported, clients should implement
* their own help listener
*/
@Deprecated
public static void setHelp(IAction action, final IContextComputer computer) {
WorkbenchHelpSystem.getInstance().setHelp(action, computer);
}
/**
* Sets the given help contexts on the given control.
* <p>
* Use this method when the list of help contexts is known in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param control the control on which to register the contexts
* @param contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>)
* @deprecated use setHelp with single context id parameter
*/
@Deprecated
public static void setHelp(Control control, Object[] contexts) {
WorkbenchHelpSystem.getInstance().setHelp(control, contexts);
}
/**
* Sets the given help context computer on the given control.
* <p>
* Use this method when the help contexts cannot be computed in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param control the control on which to register the computer
* @param computer the computer to determine the help contexts for the control
* when F1 help is invoked
* @deprecated context computers are no longer supported, clients should implement
* their own help listener
*/
@Deprecated
public static void setHelp(Control control, IContextComputer computer) {
WorkbenchHelpSystem.getInstance().setHelp(control, computer);
}
/**
* Sets the given help contexts on the given menu.
* <p>
* Use this method when the list of help contexts is known in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param menu the menu on which to register the context
* @param contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>)
* @deprecated use setHelp with single context id parameter
*/
@Deprecated
public static void setHelp(Menu menu, Object[] contexts) {
WorkbenchHelpSystem.getInstance().setHelp(menu, contexts);
}
/**
* Sets the given help context computer on the given menu.
* <p>
* Use this method when the help contexts cannot be computed in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param menu the menu on which to register the computer
* @param computer the computer to determine the help contexts for the control
* when F1 help is invoked
* @deprecated context computers are no longer supported, clients should implement
* their own help listener
*/
@Deprecated
public static void setHelp(Menu menu, IContextComputer computer) {
WorkbenchHelpSystem.getInstance().setHelp(menu, computer);
}
/**
* Sets the given help contexts on the given menu item.
* <p>
* Use this method when the list of help contexts is known in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param item the menu item on which to register the context
* @param contexts the contexts to use when F1 help is invoked; a mixed-type
* array of context ids (type <code>String</code>) and/or help contexts (type
* <code>IContext</code>)
* @deprecated use setHelp with single context id parameter
*/
@Deprecated
public static void setHelp(MenuItem item, Object[] contexts) {
WorkbenchHelpSystem.getInstance().setHelp(item, contexts);
}
/**
* Sets the given help context computer on the given menu item.
* <p>
* Use this method when the help contexts cannot be computed in advance.
* Help contexts can either supplied as a static list, or calculated with a
* context computer (but not both).
* </p>
*
* @param item the menu item on which to register the computer
* @param computer the computer to determine the help contexts for the control
* when F1 help is invoked
* @deprecated context computers are no longer supported, clients should implement
* their own help listener
*/
@Deprecated
public static void setHelp(MenuItem item, IContextComputer computer) {
WorkbenchHelpSystem.getInstance().setHelp(item, computer);
}
/**
* Sets the given help context id on the given action.
*
* @param action the action on which to register the context id
* @param contextId the context id to use when F1 help is invoked
* @since 2.0
*/
public static void setHelp(IAction action, final String contextId) {
PlatformUI.getWorkbench().getHelpSystem().setHelp(action, contextId);
}
/**
* Sets the given help context id on the given control.
*
* @param control the control on which to register the context id
* @param contextId the context id to use when F1 help is invoked
* @since 2.0
*/
public static void setHelp(Control control, String contextId) {
PlatformUI.getWorkbench().getHelpSystem().setHelp(control, contextId);
}
/**
* Sets the given help context id on the given menu.
*
* @param menu the menu on which to register the context id
* @param contextId the context id to use when F1 help is invoked
* @since 2.0
*/
public static void setHelp(Menu menu, String contextId) {
PlatformUI.getWorkbench().getHelpSystem().setHelp(menu, contextId);
}
/**
* Sets the given help context id on the given menu item.
*
* @param item the menu item on which to register the context id
* @param contextId the context id to use when F1 help is invoked
* @since 2.0
*/
public static void setHelp(MenuItem item, String contextId) {
PlatformUI.getWorkbench().getHelpSystem().setHelp(item, contextId);
}
}